package com.changgou;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/***
 * @Description //TODO Swagger
 * @Author YKK
 * @Date 2019/8/19 13:24
 * @Param
 * @Version 1.0
 **/
@Configuration
@EnableSwagger2
public class Swagger {

    /**
     * 创建API应用
     * appinfo()增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例，用来控制那些接口暴露给Swagger来展现
     * 本例采用置顶扫描的包路径来定义指定要建立API的目录
     */

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.changgou.goods.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    /**
     * 创建改API的基本信息（这些基本信息会展示在文档页面中）
     * 访问地址： http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Shop Server接口文档")
                .description("查看Shop Server的接口文档")
                .termsOfServiceUrl("https://gitee.com/zkane/SpringCloudDemo.git")
                .version("1.0.0")
                .build();
    }


    /**@Api：用在类上，说明该类的作用。
    使用在Controller层Api类上，主要属性有tags(标签)、hidden(是否隐藏)、value、authorizations等。

     @ApiOperation：注解来给API增加方法说明。
     使用在Api类的接口方法上，主要属性有value(接口名称)、notes(注释)、hidden(是否隐藏)、
     httpMethod、ignoreJsonView、response、responseHeaders等等，某些属性注解可自动识别，无需配置。

     @ApiImplicitParams : 用在方法上包含一组参数说明。
     @ApiImplicitParam：用来注解来给方法入参增加说明。

     使用在Api类的接口方法上，对接口参数进行说明，@ApiImplicitParams只有一个属性value，
     @ApiImplicitParam主要属性有name(参数名称)、value(参数说明)、required(是否必需)、
     dataType(数据类型)、paramType(参数类型)、dataTypeClass、defaultValue、readOnly等。


     注意：@ApiImplicitParam的参数说明：
     paramType：指定参数放在哪个地方    header：请求参数放置于Request Header，使用@RequestHeader获取
     query：请求参数放置于请求地址，使用@RequestParam获取
     path：（用于restful接口）-->请求参数的获取：@PathVariable
     body：（不常用）
     form（不常用）
     name：参数名
     dataType：参数类型
     required：参数是否必须传	true | false
     value：说明参数的意思
     defaultValue：参数的默认值


     @ApiResponses：用于表示一组响应

     @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

      *  code：数字，例如400
      *  message：信息，例如"请求参数没填好"
      *  response：抛出异常的类

     @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

     用在实体类上，主要属性有description(描述)、parent(父类)、subTypes、value、discriminator等。

      *  @ApiModelProperty：描述一个model的属性

    用在实体类属性上，主要属性有access、accessMode、allowableValues、allowEmptyValue(是否允许为空)、dataType(数据类型)、example(示例)、hidden(是否隐藏)、name(名称)、notes、required(是否必需)、value(说明)等。

    注意：

    要保证实体类属性都有相应的get、set方法，否则swagger-ui页面上无该属性说明。


     @ApiParam      对单个参数的描述
     @ApiResponse   对HTTP相应的描述
     @ApiResponses  对多个HTTP相应的描述
     @ApiIgnore     忽略该Api
     @ApiError       发生错误时返回的信息


     **/


}
